home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 February: Technology Seed / Mac Tech Seed Feb '97.toast / OpenDoc 1.2b2c1 / OpenDoc / OpenDoc Utilities / Interfaces / ODUtils.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-01-01  |  6.3 KB  |  190 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        ODUtils.h
  3.  
  4.     Contains:    Object utility functions
  5.  
  6.     Owned by:    Jens Alfke
  7.  
  8.     Copyright:    © 1993 - 1996 by Apple Computer, Inc., all rights reserved.
  9.  
  10.     Change History (most recent first):
  11.  
  12.          <3>    11.09.1996    NP        comments
  13.          <2>     5/24/96    jpa        1292388: Added special-case ODGetDraft &
  14.                                     ODGetSession for nonpersistent frames.
  15.                                     1.1MRD: Added pragma internal.
  16.  
  17.     Theory Of Operation:
  18.     
  19.         These are useful utilities for use with objects, particularly ref-
  20.         counted objects. Some are functions rather than macros, to reduce
  21.         code size, and can be made inline later if necessary.
  22.         
  23.         ODDeleteObject deletes an object (which doesn't need to
  24.             be a SOM object) and sets the variable pointing to it to NULL.
  25.             If the pointer was already NULL, nothing happens.
  26.             
  27.         ODReleaseObject is similar, but releases the object instead of deleting
  28.             it. Use this one for ref-counted objects.
  29.         
  30.         ODFinalReleaseObject is similar to ODReleaseObject, except that it is 
  31.             meant to be used in code which is releasing the last reference
  32.             to that object.  I.E. it does an ASSERT(refcount == 1) before calling release.
  33.         
  34.         ODRelease just releases an object (if it's not NULL.) Unlike ODReleaseObject
  35.             it does not set your pointer to the object to NULL. There are a few
  36.             occasions where you'll want to use this instead, but not many.
  37.         
  38.         ODFinalRelease is analogous to ODRelease; it is like ODFInalReleaseObject
  39.             but does not reset your pointer to NULL.
  40.             
  41.         ODAcquireObject bumps the ref-count of an object, unless it's NULL.
  42.         
  43.         ODSafeReleaseObject also releases an object, but requires no Environment
  44.             parameter and can't throw an exception. It's for use _only_ in
  45.             somUninit methods, where no Environment is available.
  46.         
  47.         ODTransferReference lowers one object's refCount while incrementing
  48.             another's. It's useful in things like setters where you want to
  49.             forget about one object and remember another. It does the right
  50.             thing if either pointer is NULL or if they point to the same object.
  51.             ** This function may throw an exception in the unlikely case that
  52.                 the Acquire or Release call fails.
  53.         
  54.         ODCopyAndRelease returns a copy of an object while releasing the object.
  55.             This is useful when transferring control of an object to the caller,
  56.             but the caller has permission to modify the object. It's optimized
  57.             for the case where the ref-count of the object is 1, in which case
  58.             it just returns the original object since no copying is needed.
  59.             (This function works only on ODShapes and ODTransforms, which are the
  60.             only classes that provide a Copy method.)
  61.             ** This function may throw an exception in the unlikely case that
  62.                 the GetRefCount or Release call fails.
  63.         
  64.         ODObjectsAreEqual returns kODTrue if two pointers point to the same object.
  65.             In OpenDoc 1.0 this is the same thing as comparing the pointers;
  66.             however, in the future when we use DSOM and objects may reside in
  67.             different address spaces, it will be possible to have two different
  68.             pointers to the same object! For future compatibility, use this function.
  69.         
  70.         ODAcquirePart, ODGetDraft and ODGetSession are convenience accessors.
  71.             There's nothing magic about them, but they do save code size since they
  72.             encapsulate several SOM calls. They also simplify the appearance of code.
  73.     
  74.     
  75.         The "do...while(0)" blocks wrapped around the macros are there to prevent
  76.         syntactic problems if a macro call is immediately followed by an "else"
  77.         statement, to keep the "else" from binding to the "if" in the macro body.
  78.         The "while" loop is optimized out by the compiler and has no effect on the
  79.         flow of control or code quality.
  80.  
  81.     To Do:
  82.     In Progress:
  83.         
  84. */
  85.  
  86. #ifndef _ODUTILS_
  87. #define _ODUTILS_
  88.  
  89. #ifndef _ODTYPES_
  90. #include "ODTypes.h"
  91. #endif
  92.  
  93. #ifdef __cplusplus
  94.     struct Environment;
  95.     class ODObject;
  96.     class ODShape;
  97.     class ODTransform;
  98.     class ODRefCntObject;
  99.     class ODPart;
  100.     class ODPersistentObject;
  101.     class ODStorageUnit;
  102.     class ODDraft;
  103.     class ODSession;
  104.     class ODWindow;
  105.     class ODDocument;
  106.     extern "C" {
  107. #else
  108.     #ifndef SOM_ODStorageUnit_h
  109.     #include <StorageU.h>
  110.     #endif
  111.     #ifndef SOM_ODTransform_h
  112.     #include <Shape.h>
  113.     #endif
  114.     #ifndef SOM_ODTransform_h
  115.     #include <Trnsform.h>
  116.     #endif
  117. #endif
  118.  
  119. #ifdef PRAGMA_INTERNAL_SUPPORTED
  120. #pragma internal on
  121. #endif
  122.  
  123. void ODRelease( Environment*, ODRefCntObject* );    // Just releases, does not set ptr to NULL
  124.  
  125. void ODFinalRelease(Environment*, ODRefCntObject* );
  126.     // This should be called only when you should be the last one to release
  127.     //    this object.
  128.  
  129. #define ODReleaseObject(EV,OBJ)                     \
  130.             do{ ODRefCntObject *temp = (OBJ);        \
  131.                 (OBJ) = kODNULL;                    \
  132.                 ODRelease((EV),temp); } while(0)
  133.  
  134. #define ODFinalReleaseObject(EV,OBJ)                 \
  135.             do{ ODRefCntObject *temp = (OBJ);        \
  136.                 (OBJ) = kODNULL;                    \
  137.                 ODFinalRelease((EV),temp); } while(0)
  138.  
  139. #define ODDeleteObject(OBJ) \
  140.             if( !(OBJ) ) ; else { delete (OBJ); (OBJ)=kODNULL; }
  141.             
  142. void ODSafeReleaseObject( ODRefCntObject* );    // Needs no ev, throws no exceptions
  143.  
  144. void ODTransferReference( Environment*, ODRefCntObject *oldObj,
  145.                                                ODRefCntObject *newObj );
  146.  
  147. void ODAcquireObject(Environment* ev, ODRefCntObject* object);
  148.  
  149.  
  150. #if ODDebug || !defined(_OD_IMPL_)
  151.     ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b);
  152. #elif defined(__cplusplus)
  153.     // Optimization for OD implementation since DSOM is not in the picture yet:
  154.     inline ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b)
  155.                         {return a==b;}
  156. #else
  157.     #define ODObjectsAreEqual(a,b)    ((a)==(b))
  158. #endif
  159.  
  160.  
  161. #ifdef __cplusplus
  162. }
  163.  
  164. // Overloaded functions can only be used in C++:
  165.  
  166. ODShape*     ODCopyAndRelease( Environment*, ODShape* );
  167. ODTransform* ODCopyAndRelease( Environment*, ODTransform* );
  168.  
  169. // All of these safely return NULL if the input object is NULL:
  170.  
  171. ODPart* ODAcquirePart( Environment*, ODFrame* );
  172. ODPart* ODAcquirePart( Environment*, ODFacet* );
  173.  
  174. ODDraft* ODGetDraft( Environment*, ODStorageUnit* );
  175. ODDraft* ODGetDraft( Environment*, ODPersistentObject* );
  176. ODDraft* ODGetDraft( Environment*, ODFrame* );            // special case
  177.  
  178. ODSession* ODGetSession( Environment*, ODStorageUnit* );
  179. ODSession* ODGetSession( Environment*, ODPersistentObject* );
  180. ODSession* ODGetSession( Environment*, ODFrame* );        // special case
  181. ODSession* ODGetSession( Environment*, ODDocument* );
  182. ODSession* ODGetSession( Environment*, ODDraft* );
  183. #endif
  184.  
  185. #ifdef PRAGMA_INTERNAL_SUPPORTED
  186. #pragma internal reset
  187. #endif
  188.  
  189. #endif //_ODUTILS_
  190.